Skip to content

Add GuidedChoice to ChatCompletionRequest #1034

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Conversation

AyushSawant18588
Copy link
Contributor

@AyushSawant18588 AyushSawant18588 commented Jul 10, 2025

Describe the change
Adds guided_choice param support to chat completions

Provide OpenAI documentation link
Structured output vLLM support

curl --request post \
  --url http://localhost:8000/v1/chat/completions \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "llama3-3b",
    "messages": [
        {
            "role": "user",
            "content": "Classify this sentiment: vLLM is great!"
        }
    ],
    "guided_choice": [
        "negative",
        "positive"
    ]
}'

Copy link

codecov bot commented Jul 10, 2025

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.59%. Comparing base (c650976) to head (557eb1c).
Report is 11 commits behind head on master.

Additional details and impacted files
@@             Coverage Diff             @@
##           master    #1034       +/-   ##
===========================================
+ Coverage   86.30%   99.59%   +13.29%     
===========================================
  Files          43       34        -9     
  Lines        2387     2205      -182     
===========================================
+ Hits         2060     2196      +136     
+ Misses        302        6      -296     
+ Partials       25        3       -22     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@sashabaranov
Copy link
Owner

@AyushSawant18588 thank you for the PR! Let's rename this field to VLLMGuidedChoice to clearly indicate that this is not from OpenAI API. And also let's update the comment accordingly

@AyushSawant18588
Copy link
Contributor Author

AyushSawant18588 commented Jul 10, 2025

@AyushSawant18588 thank you for the PR! Let's rename this field to VLLMGuidedChoice to clearly indicate that this is not from OpenAI API. And also let's update the comment accordingly

So like chat_template_kwargs this is an extra_body field, hence its supported by OpenAI as well and is not vllm specific. For example:

from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="-",
)
model = client.models.list().data[0].id

completion = client.chat.completions.create(
    model=model,
    messages=[
        {"role": "user", "content": "Classify this sentiment: vLLM is wonderful!"}
    ],
    extra_body={"guided_choice": ["positive", "negative"]},
)
print(completion.choices[0].message.content)

@AyushSawant18588
Copy link
Contributor Author

@sashabaranov wanted to confirm, are the changes made in this PR fine or should I update?

@sashabaranov
Copy link
Owner

@AyushSawant18588 okay, I see the issue! I've just merged #906, let's introduce ExtraBody here instead

@AyushSawant18588
Copy link
Contributor Author

@sashabaranov most of the fields we use are on top level and since this field is widely used for the use case of structured outputs can we merge this PR?
I will raise a separate PR to include extra body in chat completions request

@sashabaranov
Copy link
Owner

@AyushSawant18588 but it's not part of official OpenAI API right? If it is, could you please point me to the documentation?

@sashabaranov
Copy link
Owner

@AyushSawant18588 we can make it .NonOpenAIExtensions.GuidedChoice to preserve type-safety

@AyushSawant18588 AyushSawant18588 force-pushed the guided_choice_chat_completions branch from a840a3c to e893d0d Compare July 13, 2025 10:09
@AyushSawant18588
Copy link
Contributor Author

AyushSawant18588 commented Jul 13, 2025

@sashabaranov do these changes look good? made NonOpenAIExtensions.GuidedChoice

@sashabaranov sashabaranov requested a review from Copilot July 13, 2025 18:25
Copilot

This comment was marked as outdated.

@sashabaranov
Copy link
Owner

@AyushSawant18588 thank you for the update, this seems like a pretty elegant solution!

Here are a few things to consider:

  1. Copilot point about ,inline not needed above
  2. The NonOpenAIExtensions is a very generic name that could apply to pretty much anything in the codebase, in that context it should be ChatCompletionRequestNonOpenAIExtensions it seems

@AyushSawant18588
Copy link
Contributor Author

@sashabaranov Can you check the changes? I renamed struct to ChatCompletionRequestExtensions cause name was getting too big but let me know if it has to be changed

@sashabaranov sashabaranov requested a review from Copilot July 19, 2025 19:53
Copilot

This comment was marked as outdated.

sashabaranov and others added 2 commits July 19, 2025 20:54
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@sashabaranov sashabaranov requested a review from Copilot July 19, 2025 19:57
Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds support for the guided_choice parameter to the ChatCompletionRequest struct, enabling integration with vLLM's structured output functionality. The guided_choice feature allows constraining model responses to a predefined set of string options.

  • Introduces a new ChatCompletionRequestExtensions struct to organize third-party API extensions
  • Embeds the extensions struct in ChatCompletionRequest to add the guided_choice field
  • Provides comprehensive documentation explaining the vLLM-specific functionality

// is used to constrain the model's responses to a controlled set of options,
// ensuring predictable and consistent outputs in scenarios where specific
// choices are required.
GuidedChoice []string `json:"guided_choice,omitempty"`
Copy link
Preview

Copilot AI Jul 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding validation for the GuidedChoice field to ensure it contains at least one option when provided, as an empty array would not be meaningful for constraining model output.

Copilot uses AI. Check for mistakes.

@sashabaranov sashabaranov merged commit 4f87294 into sashabaranov:master Jul 19, 2025
1 check failed
@sashabaranov
Copy link
Owner

Thank you!!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants